Skip Headers

Oracle® Database Data Cartridge Developer's Guide, 10g Release 2 (10.2) Part Number B14289-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 18 Cartridge Services Using C, C++ and Java

This reference chapter describes cartridge services available to programmers using C/C++ and Java.

This chapter contains these topics:

- OCI Access Functions for External Procedures

- Installing Java Cartridge Services Files

- Cartridge Services-Maintaining Context with ContextManager Class

See Also: Oracle Call Interface Programmer's Guide for more details on cartridge services using C

## OCI Access Functions for External Procedures

When called from an external procedure, a service routine can raise exceptions, allocate memory, and get OCI handles for callbacks to the server. To use the functions, you must specify the `WITH` `CONTEXT` clause, which lets you pass a context structure to the external procedure. The context structure is declared in header file `ociextp.h` as follows:

    typedef struct OCIExtProcContext OCIExtProcContext;

This section describes how service routines use the context information. These routines are summarized in Table 18-1.

See Also: The chapter on external procedures in the Oracle Database Application Developer's Guide - Fundamentals. for more information and examples of usage.

Table 18-1 Summary of OCI Access Functions for External Procedures

Function | Description
--- | ---
OCIExtProcAllocCallMemory() | Allocates n bytes of memory for the duration of the external procedure call.
OCIExtProcRaiseExcp() | Raises a predefined exception.
OCIExtProcRaiseExcpWithMsg() | Raises a user-defined exception and returns a user-defined error message.
OCIExtProcGetEnv() | Enables OCI callbacks to the database during an external procedure call.

### OCIExtProcAllocCallMemory()

This service routine allocates n bytes of memory for the duration of the external procedure call. Any memory allocated by the function is freed as soon as control returns to PL/SQL.

Note: Do not use any other function to allocate or free memory.

The C prototype for this function follows:

    void *OCIExtProcAllocCallMemory(
       OCIExtProcContext *with_context,
       size_t amount);

The parameters with_context and amount are the context pointer and number of bytes to allocate, respectively. The function returns an untyped pointer to the allocated memory. A return value of zero indicates failure.

### OCIExtProcRaiseExcp()

This service routine raises a predefined exception, which must have a valid Oracle error number in the range 1..32767. After doing any necessary cleanup, the external procedure must return immediately. (No values are assigned to `OUT` or `IN` `OUT` parameters.) The C prototype for this function follows:

    int OCIExtProcRaiseExcp(
       OCIExtProcContext *with_context,
       size_t error_number);

The parameters with_context and error_number are the context pointer and Oracle error number. The return values `OCIEXTPROC_SUCCESS` and `OCIEXTPROC_ERROR` indicate success or failure.

### OCIExtProcRaiseExcpWithMsg()

This service routine raises a user-defined exception and returns a user-defined error message. The C prototype for this function follows:

    int OCIExtProcRaiseExcpWithMsg(
       OCIExtProcContext *with_context,
       size_t error_number,
       text   *error_message,
       size_t  len);

The parameters `with_context`, `error_number`, and `error_message` are the context pointer, Oracle error number, and error message text. The parameter len stores the length of the error message. If the message is a null-terminated string, len is zero. The return values `OCIEXTPROC_SUCCESS` and `OCIEXTPROC_ERROR` indicate success or failure.

### OCIExtProcGetEnv()

This service routine enables OCI callbacks to the database during an external procedure call. Use the OCI handles obtained by this function only for callbacks. If you use them for standard OCI calls, the handles establish a new connection to the database and cannot be used for callbacks in the same transaction. In other words, during an external procedure call, you can use OCI handles for callbacks or a new connection but not for both.

The C prototype for this function follows:

    sword OCIExtProcGetEnv(
       OCIExtProcContext *with_context,
       OCIEnv    **envh,
       OCISvcCtx **svch,
       OCIError  **errh);

The parameter with_context is the context pointer, and the parameters envh, svch, and errh are the OCI environment, service, and error handles, respectively. The return values `OCIEXTPROC_SUCCESS` and `OCIEXTPROC_ERROR` indicate success or failure.

"Doing Callbacks" on page 5-7 shows how `OCIExtProcGetEnv` might be used in callbacks. For a working example, see the script extproc.sql in the PL/SQL demo directory. (For the location of this directory, see your Oracle installation or user's guide.) This script demonstrates the calling of an external procedure. The companion file `extproc.c` contains the C source code for the external procedure. To run the demo, follow the instructions in `extproc`.`sql`. You must use the SCOTT/TIGER account, which must have `CREATE` `LIBRARY` privileges.

## Installing Java Cartridge Services Files

The `ODCI.jar` and `CartridgeServices.jar` files must be installed into the `SYS` schema in order to use the Java classes described in this chapter.

If you installed the Java option, then you must install the `ODCI.jar` and `CartridgeServices.jar` files. You do not need to perform this task if you did not install the Java option.

To install `ODCI.jar` and `CartridgeServices.jar` files, run the following commands from the command line:

    loadjava -user sys/PASSWORD -resolve -synonym -grant public
    -verbose ORACLE_HOME/vobs/jlib/CartridgeServices.jar

    loadjava -user sys/PASSWORD -resolve -synonym -grant public
    -verbose ORACLE_HOME/vobs/jlib/ODCI.jar

Substitute the `SYS` password for `PASSWORD`, and substitute the Oracle home directory for `ORACLE_HOME`. These commands install the classes and create the synonyms in the `SYS` schema.

See Also: the Oracle Database Upgrade Guide for further details on installing the `jar` files.

## Cartridge Services-Maintaining Context with ContextManager Class

The Java cartridge service is used for maintaining context. It is similar to the OCI context management service. The `ContextManager` class should be used when switching context between the server and the cartridge code.

`ContextManager` class extends `Oracle` class, which extends `Object` class.

Class Interface

    public static Hashtable ctx extends Object

Variable

    ctx public static Hashtable ctx

Constructors

    ContextManager public ContextManager()

Acccessor Methods

The following accessor methods are available in class `Oracle`.

    setContext();
    getContext()
    clearContext()

### ContextManager()

Constructor.

    ContextManager public ContextManager()

### CountException()

Constructor that extends `Exception`.

    Class oracle.CartridgeServices.CountException

### CountException(String)

Constructor that extends `Exception`.

    public CountException(String s)

### InvalidKeyException()

Constructor that extends `Exception`.

    public InvalidKeyException(String s)

### InvalidKeyException(String)

Constructor that extends `Exception`.

    public InvalidKeyException(String s)